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= | oo ¢ 

= ee Gilbert Dy From: Roger Wainwright 4 
COCATION. Vancouver Branch LOCATION & OATE: HQ. - June 6, 1980. | o . hd 
CARGONS: © DEPARTMENT: Customer Support Services © 


susect: 0S/3 MIRAM 





Some considerable while ago Owen Townsend asked me if 1 could get 
him a working paper on OS/3 MIRAM. Well here it is at last. 


Because it's dated 1/6/78 there may be some inaccuracies, but if 
youtre looking at the thing from the point of view of getting a 
better insight than can be gleaned from standard manuals, I have 
no doubt it'll serve a useful purpose. 


(I'm assuming that you won't be coding an assembler program to use 
the imperatives since, as. far as I know, the assembler interface 
to this access method is not currently supported; ) 


=@ | | | Good Juck! : 
/Sww ; | | R. Wainwright. ; | 


Encl. 
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1 
| SECTION “NO; 


SPECIFIC CARBONEES: 


eo@react: a 

EARTRACT: | | 
This paper describes a separate new disk access method for OS/3. This 
method is specifically designed to include support for -2NS'74 COBOL 
(relative and indexed I/O) and also to Support ‘the IRAM file structure.. 
Appendix A — glossary of terms = 


Ippendix B - DTF layout; DSECT label definitions; DIF field definitions 


Changes in this revision are denoted by a vertical line in the right-hand 


margin. 
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INTRODUCTION . 

MIRAM (enhanced IRAM) esouiees additional facilities beyond 
those of IRAM, which is described in Working Paper #675. It 
isa complete disk access method, based on data records that 
do not move from original pilacenane heeaedons and based on 
reer addressing by use of file relative record number. 
seope | | 
MIRAM is a comprehensive disk access method in which a: 
Single processor provides tie esceneies operations- for 

SAM, DAM, and multi-key ISAM processing; including capabilities 


for deletion, variable length records and duplicate keys. 


The processor will be able to process files created by IRAM, 
but programs which interface with IRAM will have to undergo 
changes a order to iutestace with MIRAM due to its new 
declarative and imperative macro architecture. MIRAM will 
be able to create files which can be accessed by IRAM as 
long as the resulting files involves no functionality which 
IRAM does not provide (e.g. deletion, multi-key, werdanre 
length records) . | 

Purpose 

MIRAM is developed for the support of disk access for RPG 
in the IBM System/3 manner, for ANS'74 COBOL relative and 
indexed files, and for projected use by SUL and Library 


handling programs. 
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2.0 COMPONENT DESCRIPTION 
= A single processor handles all functions, permitting the ne 
‘to intermix input and output, sequential and random, keyed 

and unkeyed operations. Within a single job, the user can 
employ all functions. | = | | Sie 

The file may be used for strictly non-indexed purposes, for 
indexed and non-indexed combined, or as an index facility 
alone, independent of data. Up to five separate index 
structures can be requested. Key sizes may range from 

1 through 80 bytes. Keys may be individually specified 

as allowing for duplication, and allowing for change during 
update. A duplicate key series is returned sequentially 

ies | in FIFO order (first in first out). | 

Means are provided to establish a position in the file, from 
Which sequential retrieval aaa be requested. Once established, 
this position can be disestablished, changed, or held constant 
during digressions into random operations. The “held” position . 
is unchanged by output, update, delete, and random retrieve 
with hold. 

The position is changed by success (or undefined by failure) 
during operations of select, sequential retrieve, and random 


retrieve without hold. 
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When the user elects to have variable length records, the 
first 4 bytes of his record must be dedicated to control 
purposes. Bytes 1 and 2 nase contain the record size in 
binary. For example, a value of 44 would: leave 40 bytes 
for user data. 7 
If the user wishes to employ the delete Sued ee ey inter- 
mix keyed and unkeyed records, he ‘must call fora record 
control byte (RCB) . For variable length records, if the 
RCB is elected, byte 3 of the record would be used by the 
system as the RCB. For fixed length records, if the RCB 
is elected, the user must predicate his data buffer size 
on the one byte larger record slot size. However, his 
specification of record size is not to include the RCB. 
MIRAM provides a new declarative macro and a new set of 
record handling imperative macros. The imperative macros 
are more specific than those of IRAM, because they do not 
depend on mode settings placed in the DIF. The basic 
operations are the same as berore, with deletion added. 

- Output a new record. | 

- Input an existing record. 

- Select a position for sequential. 

- Update an existing record. 

. Delete an existing record. 
The index-only facility can be used to force several indies 
entries to point to a single data record, or to cause indexing 
to a data record not containing the key(s) on which it is 
indexed. The index-only functions operate only on the index 


entry, which consists of the key and 3 byte pointer. 
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COMPONENT: 
Output 


When deletion capability is elected, the processor has new & 
functionality for the random output of new records. If 

the user directs a record to a point beyond current file 
end, any resulting gap will be filled with void records. 

If he directs a record to point short of file end the 
operation will be rejected if a non-void record is found 
re Belne: | 

In MIRAM, the user may output records to a file that con- 
tains index records or index entries, directing that they 
not be indexed. Such records will be marked as unkeyed. 
Either keyed or unkeyed records may be directed to selected 
positions, or to end of file. There is a switch that can 
be set to cause a follow up to.a record output that in- @ 
terrupts sequential input. Follow up consists of re- 
retrieving the last retrieved sequental record. 

If there is keyed output, there will bale report as to the 


duplication of keys that has resulted. 


For output, the new record must always be provided in a 


work space. After output, the relative record number of 

the newly placed record is available to the user. | 
Input 

The input meee proves. for choosing random or Seaueaeded. 
and keyed, index-only or unkeyed. There is also a choice 
for random with-hold, which will prevent the loss of a 
current sequential position. If keyed or index-only input 
is used, there will be a report stating that the next record 


of the key set has/has not a duplicate key. 





; 
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The user is required to forecast the use of the input 
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record: for information, for changes, or for total. 
replacement. For total replacement, the record will not 
be moved from the buffer to workspace. | When "information" 
is forecast, update or delete is not allowed to follow. 
Recognizable void records are bypassed in sequential; 
treated as no-~finds in random. | 

A successful random-without-hold can be followed by 
sequential progress to records beyond. 

Select 

New functionality has been added to the selection process. 
BOF and EOF are now available. Other specifications are 
equal (EQ), greater than (GT), and greater or equal (GE). 
Failure to satisfy the request will result in a no-find 
report, whether caused by an empty file or other reasons. 
If the request is select-by-key or index-only, success will 
be accompanied by a report avating chat the record beyond 
has/has not a duplicate key in the set referenced. | 

By a special means, the user may select by key, using only 
the n leftmost bytes of argument, where n is less than 
declared key size. | 


Changing the key of reference is done thru the SELECT macro. 


Update 


MIRAM update of keyed records is considerably more complex 
than IRAM, since keys are permitted to change. This may 


require that index adds and deletions be effected. 






UNIVAC - OFTWARE | 
AYSE | nobel tro 


=< Variable records are permitted in MIRAM. Record size may 
be changea during update, but not to exceed slot size, nor e 
to fall below the size that will encompass all keys. 
Delete 

The function to delete is new. It consists of marking 
the record ae void, and of also voiding any index entries 
Seineine- to Les | 

Erase 

The function to erase is new. The user can erase an 
entire file, thus simulating the INIT specification on 
the //LFD job control statement. In addition, for files 
which contain only unkeyed records, the user can erase 
all records starting with a specified relative record 


number. | ® 
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HARDWARE REQUIREMENTS 


A MIRAM file must reside on from one to eight disk packs 
of the same type. 
A Seceren using sua oe more MIRAM files (and in addition 
any IRAM files) must be linked to one of the two resident — 
processing modules. There is the "maximum" module which 
will permit all functions, and also a "non-indexed" 
module which can be linked in when index operations will 
not be performed. 

D3SM111 - maximum module 

D3SM0GB - non-indexed module. 


For each file, the program must provide at least the 


following: 
Register Save Area 72 
DTF Area , | (approx. 400) 
Record Work Area SLOT SIZE. 
Key Argument Area? LARGEST KEY SIZE+3 
(6 MINIMUM) 
Seek Address Area” | 4 ; 
Contiguous Buffer Area: | 7 
Min index puffer! -_ | 256> 
Min data buffer | 256° 


1. Required only if keyed or index-only operations are to 
be Sercormed: | 

26 Always required. | | 

3. All buffers must be multiples of 256 bytes. See BFSZ 
keyword description for minimum value determination. The 


puffer areas must start on a half-word boundary. 
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INTERFACE REQUIREMENTS oe : 
The MIRAM processor system utilizes OS/3 Transient ea hee 
for activation of selected processing functions, and the 

System Access Technique (SAT) for all I/O requirements and 


to maintain a device independent mode of operation. 


All user interfaces are maintained through the DIFMI 


(Define the File Multi-Index), declarative macro, and 


* selected imperative macro instructions. These interfaces 


are detailed in Section 4.4. 
‘Operator communication is maintained through output of 
error and status information .to the operator console and/or 


system message log. 


hetukad Subtest deipeenbe 
MIRAM requires file initialization and termination procedure@ 
supplied via the file OPEN and CLOSE transient facilities. 
These functions are iataacea by the users OPEN and CLOSE 
imperative macro instructions. 


Linkage to the SAT processor is provided through the DTF 
table; the address of the SAT processor is established 


during file initialization. 

Data Base 

All files to be accessed by the MIRAM processor system must 
have been created by the MIRAM or IRAM pioceeeeee. Files 
created under any other OS/3 access methods are not compatible 
with MIRAM processing requirements; MIRAM files are not 
weoessed through other OS/3 access methods, except for IRAM, 
and then only if the file was created with functionality. 


provided by IRAM. . 
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Operator Interface 
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Operator communication will be limited to the display, by 


the MIRAM system, of appropriate error/status messages. All 


communication is supplied by the OS/3 DMS message handling 


routine. These messages are outlined in the = User 
Guide (UP-8068, current version, Ronenaie B). 

User Interfaces . . . 

Declarative Macro (DTFMI) 


The DIFMI macro instruction is provided for definition of 
file characteristics. The following (ist. Sutitnes all of 
these keyword parameters, and detailed descriptions of each 
keyword follow it, with additional keyword spellings provided 
in parentheses. (Appropriate PNOTE's will be generated if 


errors are detected in keyword processing). 
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= Format: 
LABEL OPERATION OPERAND | a e 
| filename DTFMI. EXC 
EXCR 
SRDO 
ACCESS = SRD 
SUPD 
SADD 
»BFSZ=n* 


*Additional spellings 


are provided. 


& 


[ ,EOFA=symbol | 

[ ,ERRO=symbol | 

[ ,INDA=symbo] | 

[ ,INDS=n] *— 
, LOAL=symbol 
, 10A2=symbol | 


: , LORG= (x) ] 1) « | 
,KARG=symbol 
eae 


[_LocK=no | 


,MODE= {SEQ 
| RAN 
| RANE - 


[,OPTN=YES | x 


,PROC=(KEY 
UNK 
LNDO 


& RCB=NO | 


— e ay 


ne . 
_,SKAD=symbol * 
([_,-VMNT=ONE | 
(,vRFY=YEs | 
[_,WORK=YES | 


+ 


+ 


+ 


+ 
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= - PARAMETERS: 


feted 


® ACCESS=EXC -— Exclusive use of the file is requested. No other 
access of the file will be granted once it is dedicated 
to the requesting DTF. 


EXCR - Exclusive Read use of the file is requested. The DIF 
declares itself as the exclusive update, add owner of 
the file but will allow it to be shared with others 
performing read functions. 


SRDO - Shared Read-Only access to the file is requested. The 
-DTF declares itself as a reader but will only tolerate 
other readers to have access to the file. 


SRD -— Shared Read access to the file is requested. This 
declaration identifies an intention to perform only read 
access to the file. It indicates a willingness to share 
the file with any other type of access (read, update or 
add). . 

Y + : 

SUPD - Shared Update access to the file is requested. This 
“ specification identifies an intent to update the file but 
declares that it will not be extending it. The file can 
be shared by other reader DTfs. 


| 
— e _ SADD - Shared Add access to the file is requested. The DIF 
declares an intention of extending the file. The 

| | | file may be shared. with other readers. 


Ro am + ome - 


: BESZ=n ~ Specifies the size of the data buffer in “the file, 
' (BLKSIZE where n is the size, in bytes. This keyword is always 
| BKSZ) required. Size must be at least 256 as well as a 


{ 
a multiple of 256. 
The minimum value can be determined as follows: 


e If the slot length is less than or equal to 256 and 
evenly divisible into 256, the size is 256. 


e If the slot length is greater than 256 and a multiple 
of 256, the size is equal to the slot length. 


| e If the slot length is not evenly divisible into 256. 
‘ . we and not a multiple of 256, the size can be calculated 
, by adding 255 to the slot length and rounding ap \to 


ae 


~%\ 


the next multiple of 256. 





_®@ EOFA=symbo 1 - Specifies the address of a routine the user has 
eee (EOFADDR) coded to handle end-of-data for a sequential by key or 
consecutively processed file, where symbol is 

the symbolic address to which data ‘management ivenntans 
control on sensing the end of data. 
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Tie PARAMETERS: (Cont'd) 


ERRO=symbol - Specifies the address of the user's error-handling ro@@ne 
(ERROR) to which Data Management transfers control for all 

: oo conditions of error or exception to exact performance of 
the requested function. When Data Management transfers 
control, filenameC contains information on the reasons 
for the error. (See UP-8068, Data Management User Guide 
Table B-1 for error messages, and Table B-3 under DTFIS 
for significance of bits in filenameC). If omitted, 
control returns to the user inline. | 


INDA=symbol - Specifies the location in main storage in which index 
blocks are processed during keyed operations, where 

(INDAREA) symbol (address) is the location. Must be half-word 
aligned. The length of the area is specified by the 
INDS keyword. This area must immediately precede the 
primary I/O buffer (IOAl1). In order for index operations 
(keyed or index only) to be permitted, all of the index 
related keywords must be specified: INDA, INDS, KARG, and 
KEY1. If any are missing, it will be assumed that index 
operations were not intended to be employed, and no index 
operations will be permitted. (See KEYn keyword for 
single exception to this rule.) 


— INDS=n - Specifies length of index area in main storage (INDA | 
— keyword), where n is the length, in bytes. The leng 
(INDSIZE) must be at least 256 bytes and in addition, a multipl 


of 256. Required for all index operations. 





IOAl=symbol - Required to specify the location of the I/o area where 
symbol (address) is the location. Must be half-word: 
(IOAREA1) aligned. Must be greater than or equal to 256 bytes, 
a multiple of 256, and consistent with the BFSZ speci- 
fication. Must immediately follow the index buffer 
(INDA) if it is specified. Must immediately precede 
the secondary I/O buffer (IOA2) if it is specified, unles 
= index operations are not to be performed. A file which 
can perform index iQperatsons must have all buffers con- 
tiguous. 


IOA2=symbol - Specifies the location of additional I/O area, where 
symbol (address) is the location. Must also be halfword 
(IOAREA2) aligned and of the same size as the required area specifi 
; by the IOAl keyword. If index operations can be per- 
formed, this buffer must.immediately follow the primary 


I/O buffer (IOA se of a secondary buffer.is only 
permitted when performing sequential output (keyed or 


unkeyed) or unkeyed sequential input operations. 
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IORG=(r) - Required to specify the general register to be used to 


= 6 (ILOREG) point to the current record when the user is not 


on. 
ea renece 


referencing records in the work area, where r is the 
number of general register. Registers 2 through 12 are 
available. Either IORG or WORK must be specified, but 
not both. (If both specified, WORK will be used). 


KARG=symbol - Specifies the field in. the user's program where he will 
(KEYARG) Place the keys to effect retrieval of records, where 
| - symbol (address) is the location of this field. The 
length of the KARG area is equal to largest key length 
plus 3 (6 minimum). Required for all index operations. 


ou (= (0) [Fa 


Specifies one of up to 5 keys for an indexed file 
(lén¢5). Permitted size(s) is 1 through 80 bytes. 
Location (1) specifies the number of bytes preceding 
the key. If location is omitted, 9 assumed for fixed 
records, 4 for variable. DUP specifies that duplicate 
keys are allowed (NDUP indicates they are not allowed 
and is the default). CHG specifies that key can change 
during update (NCHG indicates it cannot and is the de- 
fault.) Required for all index operations unless user 
wishes to “accept" the key specifications that were 
employed to create the file. In that Case no KEYn 
specifications should be present. 


LOCK=NO - Specifies that the file lock applied to a lockable file 
at OPEN time be set for read-only and that no output 
functions be allowed to the file. If omitted from the 
DTF for a lockable file, a write-only lock is set, and 

no other task may have access to the file while it is 
open under this DTF. Ignored if specified for a non- 
locable file. : 


(A lockable file is one which has been assigned the 6- 
character prefix to the file ID, using the LBL job contro 
statement). 


MODE = SEQ - DTF is set for sequential operations should corresponding 
positional parameter be defaulted on OUTPUT or INPUT 
macros. (Default case). | 


RAN - Random operations 
RANH - Random with hold (if appropriate) operations 






eeeenner 


OPTN=YES 
(OPTION) 


PROC = KEY 


LINDO 


RCB=NO 


RCFM=FIX 
(RECFORM) 


VAR 


RCSZ=n 
(RECSIZE) 
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Specifies that the sequentially processed file is an 
optional file: one the user anticipates will not in- 
variably be present for every program execution. When 
specified for file not allocated to a device by the job 
control DVC statement, transfers control to the user's 


_EOFA routine on the first issue of an input function or 


inline and with no error upon issuing an output function. 


DTF is set for keyed operations (index and data) should 
corresponding positional parameter be defaulted on 
OUTPUT, INPUT, or SELECT macros. (Default case) 


Non-keyed operations (data only) 
Index only operations 


This specification only applies to files which are 
being newly created and it indicates that each record 
is not to contain a record control byte. Therefore, 
the DELETE macro will not be permitted. (The default 
is that_each record will contain an RCB.) At close 
time, the format label will be marked to indicate 
whether or not the RCB is present. For existing files, 
the format label indication will override this DTF speci- 
fication. The RCB is aiso necessary in order to cre 

a mixed file (e.g., one which contains unkeyed record 
as well as keyed or index only records). 


Specifies that fixed length records will be used. fTfhis 
is the default case should the keyword be omitted. 


Specifies that variable length records will be used. Th 
record size specification will pertain to a slot size . 
where the first 4 bytes of the slot are overhead, and th 
first data byte is the fifth of the slot. 


Specifies the length of each record, where n is the leng 
measured in bytes. This keyword is always required. 
(If variable records, specify the maximum size). 


The record size specification should include the 4 byte 
overhead required for variable length records but should 
not include the l’* byte RCB required for the delete or 
intermix (i.e., keyed and unkeyed records) capabilities. 
(If the RCB is requested along with variable length 
record support, the third byte in the 4 byte overhead 
will be used as the RCB.) 
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SKAD=symbol —- Specifies the location in the user's program into which 


(SEEKADR) 


VREFY=YES ~ 


(VERIFY) 


4 


he loads the relative disk address for use in processing 


files by relative record number. The form of the record 


address is a 4 hyte value. The first record is relative 


record #1. This — is' always required, 


Specifies that Data Management is to check parity of 
output records after they have been written to disk. 
Necessarily increases execution time for output functions 
by about one rotation period per block. If bad parity 


.is detected, Data Management sets the output parity 


VMNT=ONE - 


WORK=YES - 
(WORKA) 


check flag (byte 2, bit 2) in £filenameC and transfers 
control to the user's error routine or to him inline. 
If omitted, no output parity verification will be done. 


Specifies that the file is to be processed with only one 


‘volume online at any time. A file which is created in 


this manner must be processed likewise and files can 
only be processed with one volume online at a time if 
they were created that way. Non-keyed random operations 
will not be permitted. | | 


Specifies to Data Management that the user will be 
processing input or output records in a work area and 
not in the I/O area. The IORG Keyword cannot be 
specified when the WORK Keyword is specified. The 
address of the work area is specified with each issue 
of the appropriate macro. Required for all output 


and keyed update and delete functions. 
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4.4.2 Imperative Macros © 


All functional capabilities are initiated by issuing the 
appropriate imperative macro instruction. Imperative macros 
are supported to perform file initialization and termination, 
I/O processing, and dynamic file table modification. All 

_ error and exception conditions are reported to the user as 
Gefined by the ERRO keyword parameter. 

4.4.2.1 OPEN Macro 

The OPEN imperative macro initializes the data file and DTF 
table for subsequent processing. Standard labels ave pro- 
cessed and validated; the DTF table is enupaacea and completed 


for subsequent file access. If the DTF supports index op- 


i) 


ait 


erations, OPEN establishes KEY1 as the initial key of ret-@ 
erence. 

FORMAT : | | | 

abe: | OPEN = : or /£i1ename-n| 


= od 
positional parameter 1: always required. 
REPLIES : | 
Reports of unsuccessful completion are: 


: | Invalid DTF 7 

Invalid DTF specification 

Illegal Record Size 

Illegal Block size 

Illegal key specifications 

Open issued to an opened file 

FCB not found/invalid | 

Format - 1 label not found 

Partition invalid for specified DTF a) 


; 
. 


3 
3 









a 
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4.4.2.3 
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CLOSE Macro 


Upon completion of file processing, the CLOSE macto is 
issued to complete and/or terminate processing of the 
file. All standard file labels are created or updated. 
Further access of the file is inhibited. 


FORMAT: 


ion CLOSE filename-1l | pew aca filename-n | 
(1) , 
) 1 


positional parameter 1: always required 


REPLIES: 
Reports of unsuccessful completion are: 
NONE 
FEOV Macro 
The FEOV macro provides, the capability to terminate processing 
on the current volume of the file for files processed with 
only one volume online at any time (see VMNT keyword parameter) 
If the FEOV macro is {ueued for a file with all volumes mounted 
the macro is ignored. ~ 


FORMAT s 


tebe | — — FEOV filename 
| (1) 
1 
positional parameter 1: always required 
When FEOV is issued, the current volume is closed and a mount 
message is issued requesting that the next volume of the file 


be mounted. The new volume of the file is opened for processir 


subsequent macros continue processing on the new volume. 


oom + 





4.4.2.4 
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REPLIES: . ® 
Reports of unsuccessful completion are: 
Hardware error accessing FCB or ERB 

OUTPUT Macro 

The OUTPUT macro provides for placement of a new record 


in a file. 


FORMAT: | | a 7 
[raves] OUTPUT filename ’ workarea ; UNK » | SEQ | 
(1) (Z) KEY RAN 
. ow g INDO RANH 


positional parameters 1 and 2: always required 

positional parameters 3 and 4: The concept of a “long-form" 
and "short-form" macro will be introduced here. The long-form 
implies that certain optional parameters are all specified 


(e.g., for the OUTPUT macro, parameters 3 and 4). The shoft- 


form implies that none of these special optional parameters 


are specified. If a macro has more than one long-form para- 
meter, and if one is specified but not all, the macro will not 


be expanded. If the short-form is employed, the defaults will 


be obtained from indicators within the DIF. These indicators 


can be set by use of the PROC and MODE keywords of DTFMI. 
They can be changed by use of the PROC and MODE keywords of 
the APPLY macro. Use of the long-form of the macro will mice: 
change these indicators in accordance with the long-form 


parameter specifications. 
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record is not to be indexed. (Primarily for files 
without keyed records or index-only entries, but if 
the RCB exists, may be used to place a non-indexed 
record in a file which contains keyed records and/or 
index-only entries. 


record is to be indexed according to the key(s) of 
the file specification. There will be one index 


entry (which points to the record via a relative 


record number) for each key in the file. 


an index entry (which consists of a key and 3 byte 
pointer) will be added to the file. Both the key 
and pointer must be supplied. (Positional parameter 
4 is ignored). | 


record is to be placed at end-of-file and its record | 


number made available to the user. 


record is to be placed in a relative slot according 

to the record number given in SKAD. However, this 
operation is sensitive to the presence or absence of 
the RCB. When present, an attempt to overlay an 
existing record will be rejected, with an error report. 
Also, placement beyond file end will cause any gap 
created to be filled with void records. When absent, 


these two services are not available. 


(same as RAN specification). 
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The execution of OUTPUT does not affect the current se- 


If the user has caused setting of the OUTF action switch 


quential position or current reference key. 


(see APPLY macro), there is a follow up to the new record 
placement; consisting of reverting to the current sequential 
record and making that record available again. 
REPLIES : 
Reports of unsuccessful completion are: 
Illegal record size 
Illegal key value 
Overlay of existing record (if record control byte pres 
Undefined sequential positions, and OUTF requested 
Insufficient file space 
If the operation is successful, status will note the keys 


where legal duplication has occurred. Also, the record 


number (of the new record) will be placed in the seek addfess 


field.- 









UN 
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2@ 4.2.5 INPUT Macro 


The INPUT macro makes a record available for processing. It 
also permits the user to state his intentions with’ respect 


to subsequent processing. 


FORMAT: a = - 
| Label | | INPUT filename _| Jworkarea INF UNK SEC 
| (1) ) (S) MOD }j)|{ KEY))< RAN 
1 fs. REP{/ {.\tnpoj |RANE 


positional parameter 1: always required 
positional parameter 2: if specified, the record will be moved 
from the buffer to the area; otherwise, the record will be 
pointed to, in the buffer, by a specified register. Must be 
specified if there is intent to update a keyed record or when 
= retrieving via the INDO specification. 
positional parameter 3: optional specification; default is INF 
.» INF - indicates an intent to retrieve the record 
| for information purposes only; no intent to 
update or delete the record. 
- MOD - indicates an intent to modify the record in part. 
It is assumed that the user wants to inspect the 
record before changing it. Workarea or the I/0 
register will be employed according to user 
specification. 
REP ~ indicates an intent to replace the entire record. 
The record will not be moved into the workarea, as 
| it is assumed that the user already has a replace- 
. ment in the workarea which cannot be overlayed. 
positional parameters 4 and 5: long-form parameters (see 
positional parameters 3 and 4 under OUTPUT macro des- 
cription). 
| @ | . UNK - calls for unkeyed retrieval 


= - KEY - calls for keyed retrieval. Record is retrieved 
based on a specified key argument. 


Wal 
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« INDO - calls for retrieval of an index entry (key and @ 
: pointer) based on a specified key argument. | 


- SEQ -~ calls for a sequential access based on current 
| sequential position (keyed sequential if KEY. 

or INDO specified; next higher record number if 
UNK specified). Current sequential position will 
be modified. 2 | 

» RAN - calls for a random access per an argument provided 
by the user (in KARG for KEY or INDO; in SKAD for 
UNK). Current sequential position will be modified. 


- RANH - sqme as RAN specification except that the current 
7 sequential position will be held (not modified). 


REPLIES : 
Reports of unsuccessful completion are: 

Required work area not provided 

Record not found 

End of file reached 

Sequential position undefined. 
If the operation is successful, status will show whether e 
or not the succeeding record has a duplicate key in the 
current reference set. Status will also show whether or not 
the dcquired record isa keyed record. 


The record number (of the acquired record) will be placed 


in the seek address field. 
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= -4.2.6 SELECT Macro 


The SELECT macro prepares for making records available in 
sequential order by key or by record number. It can also 


be used to change the key of reference. | 


FORMAT . | | 
| ; EQ : . 
ftabea] sexzcn  |£ilename| | /GT PKEY UNK 
(1) y1(4GE /}) KREF ) KEY 
| 1 BOF INDO 
EOF 


positional parameter 1: always required 
positional parameter 2: required unless KREF specification 
in positional parameter 3 is used (in which case, positional 


parameter 2 is optional). 


» EQ - a no-find is returned unless an equal-key record 
® is found, or a non-void record is found at the 
= | given location. 


. GT - a find is reported if a non-void record can be 
found with value gonecae than the given key or 
record number . | 


. GE - a find is reported if either EQ or GT is satisfied. 


- BOF - for UNK, operates as a GE request with SKAD=1. 
For KEY or INDO, Operates as a GE request with 
KARG=9. 


« EOF - for UNK operates as a request for highest numbered 
record; for KEY or INDO as a request for oo 
keyed record or index entry. 


7 | positional parameter 3: not required. 


- PKEY = selection is based on n leading bytes of the 
:  KARG space, n<¢ key size. When this parameter is 
- used, register 9 must be preset with the value of 
| “nm. Cannot be specified in conjunction with the 
| : —— UNK specification. If not specified in conjunctic 
© | with KEY or INDO, the full key will be used. 
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_ . KREF - indicates that the key of reference is to be 
| changed. Register 9 must be preset with a | @ 
value n, where l<n<5. In addition, n must 
not exceed the number of keys in the file. This 
specification can be used in conjunction with 
positional parameter 2, if first, a key of 
_veference change and. then, a sequential prepar- 
ation is desired. 
positional parameter 4: long-form parameter. (See positional 
parameters 3 and 4 under OUTPUT macro description). 
. UNK - preparation is to be based on relative record — 
number. Except for BOF and EOF, preparation 
is further based on the value given in SKAD. 
» KEY - preparation is to be based on the current 
| reference key. Except for BOF and EOF, 
preparation is further based on the value 
given in KARG. 
- INDO - (same as KEY specification) 
a . REPLIES: 
If the select operation is unsuccessful, a no-find is re- @ 
ported. . The current sequential position becomes undefined, 
precluding a following sequential input. (Reference to an 
empty file also produces the no-find). If the operation is 
successful, the record-number (of the record pointed to) will 
we be placed in the seek address field, and for a SELECT which 
employs the index, the key (of the record pointed to) will be 


placed in the key argument field. 
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rr? UPDATE Macro 
The UPDATE macro causes the most recently retrieved record 


to be updated. 


FORMAT: 
paver | UPDATE filename ’ Jworkarea 
| (1) | (f) 
1 | BS 


positional parameter 1: always required 
sosttioaal parameter 2: workarea must be used in all cases 
where the existing record is keyed or an index-only entry. 
REPLIES: | 
Reports of aheiecesstul completion eee 
Record was obtained for information 
Illegal record size 
Illegal key value 
car 404.2.8 — DELETE Macre | 
The DELETE macro is used to void the record most recently 
acquired. Marks the SBqece record as void, and voids any 
index entries pointing to the record. Cannot be used for 
files without the RCB. 
FORMAT : ; 
paver | DELETE | Pitenane 
| (1). 
1 
positional parameter 1: always required 


REPLIES: 


None 
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ce 4.4.2.9 ERASE Macro 

The ERASE macro is used to erase an entire file or to erase 
part of a file (which contains only non-indexed records) 
starting from 5 teen relative record number. The RCB is not 
required to perform these functions. 

FORMAT : 


rapes | ERASE filename ’ ALL 
7 (1) 4 PART 
1 


positional parameter 1: always required 
positional parameter 2: always required 


. ALL - Causes the entire file to be discarded. Can 
be used on file which contains any kind of 
record (e.g., keyed, unkeyed, index-only). 


- PART - Causes all records, beginning with a user 
oe a specified record number (in SKAD), to be 
reine | discarded. The record, which corresponds 
) . to the record number in the seek address @ 

field, and all records whose record numbers 
are greater in value, will be discarded. 
This form of the ERASE macro can be issued 
against a file which contains only unkeyed 
records (i.e., no keyed records or index 
only entries). 


REPLIES : 2 


Reports of unsuccessful completion are: 


Invalid Macro error (if ERASE PART is specified 
and file contains keyed records or index entries). 
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APPLY Macro 
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The APPLY macro is used to apply changes to the DTF, which | 


will have an effect on subsequent processing. The changes 


will be effective until changed by another APPLY macro call. 


Code will be generated in ne at assembly time.. 


FORMAT: 


[raven] APPLY 


positional parameter 


positional parameter 


e 


TORG= (r) 


WORK=YES 


MODE= 


PROC= 


OUTF=YES 


SEQ 


UNK 
KEY. 
INDO 


, . IORG= 

filename| , WORK= 
(1) | OUTF= 

1 MODE= 
PROC= 


always required 
always required 


Will either change the I/O register 
being employed or change the DTF 
from workarea to I/O register mode. 
(See IORG keyword in DTF description 
for additional information). 


Will change the DTF from I/0 register 
to workarea mode. (See WORK keyword 
in DTF description for additional 
information). 


Will set an indicator such that following 
an add to the file, the last record re- 
trieved will be read back in order to 
duplicate the conditions which existed 
before the add. (OUTF=NO will turn off 
the indicator). | 


Will change the DTF indicators which > 
are used for the short-form macros. 

(See MODE keyword in DTF description, anc 
positional parameters 3 and 4 under OUTPI 
macro description). ; 


Will change the DIF indicators which are 
used for the short-form macros. (See 
PROC keyword in DIF description, and 


positional parameters 3 and 4 under OUTP! 


macro description). 
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FUNCTIONAL DESCRIPTION 

MIRAM provides two processing modules. The modules are ® 
reentrant; so they are limited to modifying core locations 

in the file DIF area, and user areas that are defined in the 
DIF. | | 
There are also several transients that are called as their 
services are required. In general, these are used to perform 
services that are infrequently needed. | 

File Format | — 

All MIRAM files consist of two partitions, a data and an 
index partition. Initially, there will be no allocations 

made to either of the partitions. The first output function 
‘which references a partition, will cause an initial allocation 
made to that partition. For example, if the first record ou: 
to the file is unkeyed, the data partition only will at that 
time be extended to receive an aiisencics: Then, if a keyed 
record or index only entry is output to the file, the index 


partition will be extended to receive an allocation. 
BLK 1 


BLK 2 BLK 3 BLK | 
S1 $2 83 S4 s5 


The data partition consists of 256 byte unkeyed physical 

blocks. User record slots are required to be of uniform size, 
and the size: chosen is not required to conform to the-phvateal 
block size. Consecientiy, it is possible for records to span 


physical block boundaries as illustrated by the ahove diag@n. 
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=@6 The index partition has 256 pyte keyed blocks. In both 

| partitions, the processing programs make use of the SAT 
facility for transferring several physical blocks with a 
Single access. 

Part of the work in the index partition is done by hardware 
key search, and part by multi-block transfers. The fine | 
level of index is treated as a chain of multi-sector blocks, 


not formatted for search. A three~-sector fine block is 


diagrammed below: 
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Sel File Format (Cont'd) 





Each active entry consists of a key plus a 3-byte pointer 
which gives the file relative record number of a data @ 
record. The number of active entries varies from block 

to block. The control area consists of three fields, 

totalling 6 bytes: ) 





<—1—> <3 ——_____> 


The coarse and mid levels of index are formatted for hard— 
ware key search. Areas subject to search may have in- 
sufficient entries to fill out a track. Hence, there must 
be suitable dummy entries to prevent false hits. A 
partially filled coarse/mid sector is diagrammed below: 


oS 
‘eecseena 
| Sh 


(256 byte block) 





For hardware search, the high key entry of the sector must 
be in first position. Remaining entries are in descending 
sequence. The final byte of the sector is used to contain 
the current number of active bytes. 


j When there are multiple keys, each has its own coarse 
level in the index partition. All hardware searchable 
sectors must have a front key area equal in size to the 
longest key of the group. For shorter keys, the storage 
space is filled out with appended FF bytes. 


For handling of keys where. duplicates are allowed, in the 


coarse and mid levels of index, an extra byte between the key 
and pointer is used. 


Peegooumm. 
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Function and Subroutine Procedures 








Addition of New Keyed Records 


This function performs two actions; placement of an index . 
entry in fine level index, and placement of the new data 
record at the end of the data string. The processor first 
assures sufficient index space, then tests for orderly/ 
disorderly load, and calls in the indicated transient. 

The transient handles all index modification, and returns 
to the processor. Processor coding handles the placement | 
of the data record, using the same code as for placement 
in a non-indexed case. | 


If there are multiple keys, the processor follows another 
path. On this path, there is no checking for a high key 
Situation. The processor calls n times on the transient 

.*- that will add anywhere. If all keys are added success- 
fully, the path then leads to processor: code which appends 
the new data record to the data string. 


If an illegal duplicate key is found, a transient is called 
to undo the part of the process ——w Gone. This deletes 
any index entries already made. 


S262 - Random Retrieval 


oo ‘This function retrieves a record by key or by relative 

, record number. All coding for this action is resident in 
the processor. If it is keyed retrieval, a subroutine 
conducts the index search. At conclusion, the main line 
coding usés the reported relative record number to 
retrieve the desired record. | 


Random retrieval can be followed by en update or delete 
function. 


5.2.3 Preparation for Sequential Retrieval 


The SELECT instruction allows the user to set the low limit 
of a range of records to be retrieved in key sequence or. 
consecutive sequence. If key sequence is demanded, a | 
transient is called to Beles the key search. 


— > 
7’ 
— : as = bd 
_—->. 


eee ~~ > 
° 


SELECT does not provide a record to the user. Instead, the 
user's first input function provides the first record of the 
range. 


Cendachamabd 
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5.2.4 Sequential Retrieval 


= After an input function, the user may issue an update or 
| delete function. Else he may issue another input function, & 
passing on without update. Sequential input coding is 
resident. While in a sequential mode, the user may also 
request that a new record be added. This requires that 
Data Management perform the add, then revert to the 
sequential mode as though there had not been this dis-~ 
turbance. This action is performed in a transient, 
because of the large amount of coding required. 


54265 Deleting a Record . 


Coding to mark the record is resident. Any required index 
modification is transient. | 


5.2.6. Undating a Record 


Coding to update a record is resident. Any required index 
modification is transient. 


562.7 Erasing all or part of a file 
fr cccce 
ee Coding to erase is resident. @ 


eteeenr 
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PERFORMANCE 


Every effort has been made to provide best possible 
performance under the constraints imposed by small buffer 
sizes. 


First priority has been assigned to performance during 
retrieve operations. Consecutive retrieve is accomplished 
without reference to index, and takes advantage of any 

extra buffer space provided by the user. Random keyed 
retrieve coding is part of the resident keyed modules, to 
avoid burdening each retrieve with a transient call. Keyed 
search from coarse to fine level is expected to cost 3 | 
accesses for most records of a sizeable file, and 2 accesses 
for the remainder. 

By the design chosen, operations that. add new records to 

the file maintain the index in usable form. This eliminates 
the cost of an index sort at program termination. However, 
the record-by-record cost of this method is greater than 

the immediate cost of placing a new record without index 
maintenance. It is believed that the index maintenance method 
will show good results, particularly when a file is subject 
to growth by daily addition of records. 


Disorderly load is essentially a random add process where 
the user gives a series of add commands without inter- 
spersing commands that would require writing an incomplete 


data buffer to free the space for other use. Thus, there 


is some performance advantage in the concerted series of 
adds. 


Orderly load is estimated to be better than twice as fast 
as disorderly. | | 


This results from elimination of search for the place to 
put an index entry, and from the concerted series advantage 


mentioned. 
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7.0 COMPATIBILITY 


as MIRAM must provide file and record handling services for 
disk files such that OS/3 COBOL can provide the functions e 
available to the user of ANS'74 COBOL. MIRAM must also 
be able to access and create IRAM files. 7 


8.0 CONVERSION 


Other software components requiring modifications are COBOL, 
SORT, DATA UTILITIES. These components must be capable of 
accepting a user's specifications for a MIRAM file and 
providing the interfaces to process the file according to 

the user's wishes. They must be modified to produce suitable 
MIRAM DIF tables, and to provide suitable aia calls. 


9.0 DOCUMENTAT ION AND SUPPORT 


Sections added to the User Guide UP-8068 and the Giceneiaiiane 
Reference UP-8159, will describe the MIRAM saa and 
explain its use. 


Program listings and flowcharts will be maintained to 
assist in program support. 


10.0 RESTRICTIONS 


= | -. Search keys may not exceed 80 bytes. @ 


- Buffers must start on half-word boundaries. 


. Search*keys may not contain any FF bytes on fixed 
sector disks unless these disks have the “binary 
key" feature. 


11.0 MAINTAINABILITY AND RELIABILITY 


OS/3 Physical IoOCS is the agency that detects and attempts 
to correct hardware errors during disk reference. When an 
uncorrectable error occurs, this fact is reported through 
the chain: PIOCS to SAT to MIRAM to the user of MIRAM. 

At termination of a user program, a CLOSE ALL transient is 
called, to close any files found to be still open. Proper 
closing of MIRAM files is vitally necessary when there has 
been sequential loading or sequential retrieval with up- 
Gating. In these cases, MIRAM will frequently be in a 
delayed-write status, where changes in content of the 
buffer in main memory have not yet been written to disk. 
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RELATED DOCUMENTS 


IRAM CPSD (W.P. #675), PD A-43058 (ISAM) and PD A-43061 
(SAT) may be read for background information on error - 
handling, multi-partition files, and VTOC. However, they 
currently contain no reference to MIRAM as such. 


Otherwise, there are the IBM System 3 manuals listed 
below: 


GC21-7571-2 Disk Concepts and Planning Guide 
GC21-7512-6 Control peste eee eee 
GC21-7562-2 Model 10 Disk System 

SC21-7504-5 System 3 RPG II Reference Manual 
SC21-7595-0 System 32 RPG II Reference Manual 


_ STANDARDS DEVIATIONS 


This component is designed to provide compatibility of 
services to ANS'74 COBOL and IBM System 3. Deviations 
from any applicable Sperry Univac Standards are not 
established at this time. Adoption of the solidly packed 
Gata string with records spanning physical block ends is 
not a usual practice in Univac Data Management Systems. 
However, this is not known to violate a Sperry Univac 
Standard. : | 


The method was adopted in order to provide conservation of 
disk space in the System 3 manner. . It also helps in support 
of the System 3 concept of handling a file with different 
size buffers at different times - a concept that negates 

the more common concept of a fixed size logical block. 
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Glossary of Terms: 
A. | 
appender string | 
A string of records that is enlarged on by placing : a2 new 
record at end-of-string. 

Be 

block 


The portion of a file transferred into or out of main | 
storage by a single access. - 

block splitting | 

A technique for maintenance of inserter: strings. When 
insertion into a block causes overflow, a fresh block is 
chained into Pequence, and the records are —: between 

the two blocks. 

buffer 

‘An area in main storage for handling a block of data. Must not. 
be smaller than the blocks to be handled. 

C. 

Consecative sequence . = | . 

The sequence in which records of a string are originally passed 
to Data Management by the user. In some cases, differs from 
ascending key sequence. | 

esueee Devel 

The level of a hierarchical index system that has the least 


number of entries, which subdivide the file into large sections. 





= 
De- tet -° tem 
. . . 


= . @irect addressing ) ; 





Retrieving a specific block or récord from disc storage by a e@ 
single access, -using numeric values given in a field. 


=. - - bad = ~ - ° «- 
Be-:.. _— =*. Oe a ay OP es es ee 


extent. 


A_ set of contiguous tracks on disc assigned exclusively to 


one file. Several extents may be required to provide space 


enough for a file... _-- 
Fe. 
field. neo etre ece- 

One or more contiguous characters, normally comprising a single 
unit of information. | 


= file  --- : | . = | 


Peeeee 3° .* ® 
- @ 


A delimited storage space having an identifying Eillename> ae 





for subdividing the entire data mass into manageable groups. 
‘Also, the data residing in such a storage space. 

fine level é oO _ : | : : 

The level of hierarchical index systems that has the greatest 
number of entries, providing the most detailed subdivisions of 
the file. : a 

he. 

‘inserter string | 

A string of records that may be enlarged by placing a new 


record between existing records. 
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mid: level 


Any level of hierarchical index system that falls between 

the coarse and fine levels. 

P. 

partition | 

A file subdivision, which is required to have uniform block 
specifications. OS/3 data management provides partition- 
relative block addressing, and individual partition extension 
capabilities. | 
pointer 

A field containing a value for direct addressing. 

R. 

record 

The collection of contiguous characters designated by the 
user to data management as such, for handling as a unit. 
Record size must not exceed block size. 

S. 

slot 

A filing poace, Shae may or may not be occupied by a record. 
Slots are uniform size, number consecutively from 1 ton. 

For variable size records, slot length $3 qasci mum record size 
+ 4. For fixed size records, if there is an RCB, slot length 
is record size + l: otherwise, slot length is record size. 
string of records 

A series of records having exclusive use of the blocks 


occupied, and retrievable in sequence by a series of "get" 
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instructions. 

- @ 
volume 

The largest physical unit for data storage, such as a tape 


reel or disc pack. 
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- The following unit specification is being submitted for your 
review and approval: | ae 


MULTI-INpEvedD Retwoom meeess Cu Am) 


Please document your comments on the standard Documentation 

Review Form (sample enclosed) and/or in the review document 
itself. In the latter case, reference your comments on the 
‘Documentation Review Form. | 


aT eae taw nesting: is scheduted for this facility 
FerttiteN 


on M1979 3 CLitschodm HA AT ARM. | 


Due to the limited nature of the changes described = 
this specification, no design review meeting will be 
scheduled. | 
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The purpose of the design review meeting will be to discuss 
the £unctions and interfaces of the enhancements. It will 

not be directed toward the implementation techniques except 
as they relate to the antersaces with other components. 


Please submit all eomnenes to Dd, WIAS TIN by | [n/27. 


After consideration of these comments and those raised in the. - 
Gesign review, the specification. will be updated and formal 
approval will be BEquceteds:: ‘ 


Those persons whose names are esterisked on the Distribution 
List are expected to respond. Others on the list are anvetes 
to respond if they desire to’ do so. 
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r. Buttschardt, Munager 
OS/3 Software Developinent 
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The Poiiowiag unit ‘specification is being submitted for your 
final review and approval: , 


MIRAM. 


This specification was previously submitted for review by 
your department and comments that were returned to us have 
been reviewed and, where appropriate, incorporated into this 
version. The remaining comments have been addressed 
directly with the reviewers. | 


Please sign the 445 = iscen form and forward to 
T. Gannon by: / | 
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